Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / sunrpc / xdr.man < prev

Wrap

Text File | 1989-03-31 | 20.8 KB | 529 lines

XDR C Library Procedures XDR NNAAMMEE xdr - library routines for external data representation SSYYNNOOPPSSIISS AANNDD DDEESSCCRRIIPPTTIIOONN These routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Data for remote procedure calls are transmitted using these routines. xxddrr__aarrrraayy((xxddrrss,, aarrrrpp,, ssiizzeepp,, mmaaxxssiizzee,, eellssiizzee,, eellpprroocc)) XXDDRR **xxddrrss;; cchhaarr ****aarrrrpp;; uu__iinntt **ssiizzeepp,, mmaaxxssiizzee,, eellssiizzee;; xxddrrpprroocc__tt eellpprroocc;; A filter primitive that translates between variable- length arrays and their corresponding external representations. The parameter aarrrrpp is the address of the pointer to the array, while ssiizzeepp is the address of the element count of the array; this element count can- not exceed mmaaxxssiizzee. The parameter eellssiizzee is the ssiizzeeooff each of the array's elements, and eellpprroocc is an XDR filter that translates between the array elements' C form, and their external representation. This routine returns one if it succeeds, zero otherwise. xxddrr__bbooooll((xxddrrss,, bbpp)) XXDDRR **xxddrrss;; bbooooll__tt **bbpp;; A filter primitive that translates between booleans (C integers) and their external representations. When encoding data, this filter produces values of either one or zero. This routine returns one if it succeeds, zero otherwise. xxddrr__bbyytteess((xxddrrss,, sspp,, ssiizzeepp,, mmaaxxssiizzee)) XXDDRR **xxddrrss;; cchhaarr ****sspp;; uu__iinntt **ssiizzeepp,, mmaaxxssiizzee;; A filter primitive that translates between counted byte strings and their external representations. The param- eter sspp is the address of the string pointer. The length of the string is located at address ssiizzeepp; strings cannot be longer than mmaaxxssiizzee. This routine returns one if it succeeds, zero otherwise. xxddrr__cchhaarr((xxddrrss,, ccpp)) XXDDRR **xxddrrss;; cchhaarr **ccpp;; A filter primitive that translates between C characters Sprite v1.0 3 November 1987 1 XDR C Library Procedures XDR and their external representations. This routine returns one if it succeeds, zero otherwise. Note: encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider xxddrr__bbyytteess, xxddrr__ooppaaqquueeor xxddrr__ssttrriinngg. vvooiidd xxddrr__ddeessttrrooyy((xxddrrss)) XXDDRR **xxddrrss;; A macro that invokes the destroy routine associated with the XDR stream, xxddrrss. Destruction usually involves freeing private data structures associated with the stream. Using xxddrrss after invoking xxddrr__ddeessttrrooyy is undefined. xxddrr__ddoouubbllee((xxddrrss,, ddpp)) XXDDRR **xxddrrss;; ddoouubbllee **ddpp;; A filter primitive that translates between C ddoouubbllee precision numbers and their external representations. This routine returns one if it succeeds, zero other- wise. xxddrr__eennuumm((xxddrrss,, eepp)) XXDDRR **xxddrrss;; eennuumm__tt **eepp;; A filter primitive that translates between C eennuumms (actually integers) and their external representations. This routine returns one if it succeeds, zero other- wise. xxddrr__ffllooaatt((xxddrrss,, ffpp)) XXDDRR **xxddrrss;; ffllooaatt **ffpp;; A filter primitive that translates between C ffllooaatts and their external representations. This routine returns one if it succeeds, zero otherwise. vvooiidd xxddrr__ffrreeee((pprroocc,, oobbjjpp)) xxddrrpprroocc__tt pprroocc;; cchhaarr **oobbjjpp;; Generic freeing routine. The first argument is the XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: the pointer passed to this routine is _n_o_t freed, but what it points to _i_s freed (recursively). Sprite v1.0 3 November 1987 2 XDR C Library Procedures XDR uu__iinntt xxddrr__ggeettppooss((xxddrrss)) XXDDRR **xxddrrss;; A macro that invokes the get-position routine associ- ated with the XDR stream, xxddrrss. The routine returns an unsigned integer, which indicates the position of the XDR byte stream. A desirable feature of XDR streams is that simple arithmetic works with this number, although the XDR stream instances need not guarantee this. lloonngg ** xxddrr__iinnlliinnee((xxddrrss,, lleenn)) XXDDRR **xxddrrss;; iinntt lleenn;; A macro that invokes the in-line routine associated with the XDR stream, xxddrrss. The routine returns a pointer to a contiguous piece of the stream's buffer; lleenn is the byte length of the desired buffer. Note that pointer is cast to lloonngg **. Warning: xxddrr__iinnlliinnee may return NULL (0) if it cannot allocate a contiguous piece of a buffer. Therefore the behavior may vary among stream instances; it exists for the sake of efficiency. xxddrr__iinntt((xxddrrss,, iipp)) XXDDRR **xxddrrss;; iinntt **iipp;; A filter primitive that translates between C integers and their external representations. This routine returns one if it succeeds, zero otherwise. xxddrr__lloonngg((xxddrrss,, llpp)) XXDDRR **xxddrrss;; lloonngg **llpp;; A filter primitive that translates between C lloonngg integers and their external representations. This rou- tine returns one if it succeeds, zero otherwise. vvooiidd xxddrrmmeemm__ccrreeaattee((xxddrrss,, aaddddrr,, ssiizzee,, oopp)) XXDDRR **xxddrrss;; cchhaarr **aaddddrr;; uu__iinntt ssiizzee;; eennuumm xxddrr__oopp oopp;; This routine initializes the XDR stream object pointed to by xxddrrss. The stream's data is written to, or read Sprite v1.0 3 November 1987 3 XDR C Library Procedures XDR from, a chunk of memory at location aaddddrr whose length is no more than ssiizzee bytes long. The oopp determines the direction of the XDR stream (either XXDDRR__EENNCCOODDEE, XXDDRR__DDEECCOODDEE, or XXDDRR__FFRREEEE ). xxddrr__ooppaaqquuee((xxddrrss,, ccpp,, ccnntt)) XXDDRR **xxddrrss;; cchhaarr **ccpp;; uu__iinntt ccnntt;; A filter primitive that translates between fixed size opaque data and its external representation. The parameter ccpp is the address of the opaque object, and ccnntt is its size in bytes. This routine returns one if it succeeds, zero otherwise. xxddrr__ppooiinntteerr((xxddrrss,, oobbjjpppp,, oobbjjssiizzee,, xxddrroobbjj)) XXDDRR **xxddrrss;; cchhaarr ****oobbjjpppp;; uu__iinntt oobbjjssiizzee;; xxddrrpprroocc__tt xxddrroobbjj;; Like xxddrr__rreeffeerreennccee in that it XDR xxddrr__ppooiinntteerr serial- izes NULL pointers, whereas xxddrr__rreeffeerreennccee does not. Thus xxddrr__ppooiinntteerr can XDR recursive data structures, such as binary trees or linked lists, correctly, whereas xxddrr__rreeffeerreennccee will fail. vvooiidd xxddrrrreecc__ccrreeaattee((xxddrrss,, sseennddssiizzee,, rreeccvvssiizzee,, hhaannddllee,, rreeaaddiitt,, wwrriitteeiitt)) XXDDRR **xxddrrss;; uu__iinntt sseennddssiizzee,, rreeccvvssiizzee;; cchhaarr **hhaannddllee;; iinntt ((**rreeaaddiitt))(()),, ((**wwrriitteeiitt))(());; This routine initializes the XDR stream object pointed to by xxddrrss. The stream's data is written to a buffer of size sseennddssiizzee; a value of zero indicates the system should use a suitable default. The stream's data is read from a buffer of size rreeccvvssiizzee; it too can be set to a suitable default by passing a zero value. When a stream's output buffer is full, wwrriitteeiitt is called. Similarly, when a stream's input buffer is empty, rreeaaddiitt is called. The behavior of these two routines is similar to the UNIX system calls rreeaadd and wwrriittee, except that hhaannddllee is passed to the former routines as the first parameter. Note that the XDR stream's oopp field must be set by the caller. Warning: this XDR stream implements an intermediate record stream. Therefore there are additional bytes in the stream to provide record boundary information. Sprite v1.0 3 November 1987 4 XDR C Library Procedures XDR xxddrrrreecc__eennddooffrreeccoorrdd((xxddrrss,, sseennddnnooww)) XXDDRR **xxddrrss;; iinntt sseennddnnooww;; This routine can be invoked only on streams created by xxddrrrreecc__ccrreeaattee. The data in the output buffer is marked as a completed record, and the output buffer is option- ally written out if sseennddnnooww is non-zero. This routine returns one if it succeeds, zero otherwise. xxddrrrreecc__eeooff((xxddrrss)) XXDDRR **xxddrrss;; iinntt eemmppttyy;; This routine can be invoked only on streams created by xxddrrrreecc__ccrreeaattee. After consuming the rest of the current record in the stream, this routine returns one if the stream has no more input, zero otherwise. xxddrrrreecc__sskkiipprreeccoorrdd((xxddrrss)) XXDDRR **xxddrrss;; This routine can be invoked only on streams created by xxddrrrreecc__ccrreeaattee. It tells the XDR implementation that the rest of the current record in the stream's input buffer should be discarded. This routine returns one if it succeeds, zero otherwise. xxddrr__rreeffeerreennccee((xxddrrss,, pppp,, ssiizzee,, pprroocc)) XXDDRR **xxddrrss;; cchhaarr ****pppp;; uu__iinntt ssiizzee;; xxddrrpprroocc__tt pprroocc;; A primitive that provides pointer chasing within struc- tures. The parameter pppp is the address of the pointer; ssiizzee is the ssiizzeeooff the structure that **pppp points to; and pprroocc is an XDR procedure that filters the structure between its C form and its external representation. This routine returns one if it succeeds, zero other- wise. Warning: this routine does not understand NULL pointers. Use xxddrr__ppooiinntteerr instead. xxddrr__sseettppooss((xxddrrss,, ppooss)) XXDDRR **xxddrrss;; uu__iinntt ppooss;; A macro that invokes the set position routine associ- ated with the XDR stream xxddrrss. The parameter ppooss is a position value obtained from xxddrr__ggeettppooss. This routine Sprite v1.0 3 November 1987 5 XDR C Library Procedures XDR returns one if the XDR stream could be repositioned, and zero otherwise. Warning: it is difficult to reposition some types of XDR streams, so this routine may fail with one type of stream and succeed with another. xxddrr__sshhoorrtt((xxddrrss,, sspp)) XXDDRR **xxddrrss;; sshhoorrtt **sspp;; A filter primitive that translates between C sshhoorrtt integers and their external representations. This rou- tine returns one if it succeeds, zero otherwise. vvooiidd xxddrrssttddiioo__ccrreeaattee((xxddrrss,, ffiillee,, oopp)) XXDDRR **xxddrrss;; FFIILLEE **ffiillee;; eennuumm xxddrr__oopp oopp;; This routine initializes the XDR stream object pointed to by xxddrrss. The XDR stream data is written to, or read from, the Standard II//OO stream ffiillee. The parameter oopp determines the direction of the XDR stream (either XXDDRR__EENNCCOODDEE , XXDDRR__DDEECCOODDEE , or XXDDRR__FFRREEEE ). Warning: the destroy routine associated with such XDR streams calls fffflluusshh on the ffiillee stream, but never ffcclloossee. xxddrr__ssttrriinngg((xxddrrss,, sspp,, mmaaxxssiizzee)) XXDDRR **xxddrrss;; cchhaarr ****sspp;; uu__iinntt mmaaxxssiizzee;; A filter primitive that translates between C strings and their corresponding external representations. Strings cannot be longer than mmaaxxssiizzee. Note that sspp is the address of the string's pointer. This routine returns one if it succeeds, zero otherwise. xxddrr__uu__cchhaarr((xxddrrss,, uuccpp)) XXDDRR **xxddrrss;; uunnssiiggnneedd cchhaarr **uuccpp;; A filter primitive that translates between uunnssiiggnneedd C characters and their external representations. This routine returns one if it succeeds, zero otherwise. xxddrr__uu__iinntt((xxddrrss,, uupp)) XXDDRR **xxddrrss;; Sprite v1.0 3 November 1987 6 XDR C Library Procedures XDR uunnssiiggnneedd **uupp;; A filter primitive that translates between C uunnssiiggnneedd integers and their external representations. This rou- tine returns one if it succeeds, zero otherwise. xxddrr__uu__lloonngg((xxddrrss,, uullpp)) XXDDRR **xxddrrss;; uunnssiiggnneedd lloonngg **uullpp;; A filter primitive that translates between C uunnssiiggnneedd lloonngg integers and their external representations. This routine returns one if it succeeds, zero otherwise. xxddrr__uu__sshhoorrtt((xxddrrss,, uusspp)) XXDDRR **xxddrrss;; uunnssiiggnneedd sshhoorrtt **uusspp;; A filter primitive that translates between C uunnssiiggnneedd sshhoorrtt integers and their external representations. This routine returns one if it succeeds, zero other- wise. xxddrr__uunniioonn((xxddrrss,, ddssccmmpp,, uunnpp,, cchhooiicceess,, ddffaauulltt)) XXDDRR **xxddrrss;; iinntt **ddssccmmpp;; cchhaarr **uunnpp;; ssttrruucctt xxddrr__ddiissccrriimm **cchhooiicceess;; bbooooll__tt ((**ddeeffaauullttaarrmm))(());; //** mmaayy eeqquuaall NNUULLLL **// A filter primitive that translates between a discrim- inated C uunniioonn and its corresponding external represen- tation. It first translates the discriminant of the union located at ddssccmmpp. This discriminant is always an eennuumm__tt. Next the union located at uunnpp is translated. The parameter cchhooiicceess is a pointer to an array of xxddrr__ddiissccrriimm structures. Each structure contains an ordered pair of [[vvaalluuee,, pprroocc]]. If the union's discrim- inant is equal to the associated vvaalluuee, then the pprroocc is called to translate the union. The end of the xxddrr__ddiissccrriimm structure array is denoted by a routine of value NULL . If the discriminant is not found in the cchhooiicceess array, then the ddeeffaauullttaarrmm procedure is called (if it's not NULL ). Returns one if it succeeds, zero otherwise. xxddrr__vveeccttoorr((xxddrrss,, aarrrrpp,, ssiizzee,, eellssiizzee,, eellpprroocc)) XXDDRR **xxddrrss;; cchhaarr **aarrrrpp;; uu__iinntt ssiizzee,, eellssiizzee;; xxddrrpprroocc__tt eellpprroocc;; Sprite v1.0 3 November 1987 7 XDR C Library Procedures XDR A filter primitive that translates between fixed-length arrays and their corresponding external representa- tions. The parameter aarrrrpp is the address of the pointer to the array, while ssiizzee is is the element count of the array. The parameter eellssiizzee is the ssiizzeeooff each of the array's elements, and eellpprroocc is an XDR filter that translates between the array elements' C form, and their external representation. This routine returns one if it succeeds, zero otherwise. xxddrr__vvooiidd(()) This routine always returns one. It may be passed to RPC routines that require a function parameter, where nothing is to be done. xxddrr__wwrraappssttrriinngg((xxddrrss,, sspp)) XXDDRR **xxddrrss;; cchhaarr ****sspp;; A primitive that calls xxddrr__ssttrriinngg((xxddrrss,, sspp,, MMAAXXUUNN..UUNNSSIIGGNNEEDD ); where MMAAXXUUNN..UUNNSSIIGGNNEEDD is the maximum value of an unsigned integer. xxddrr__wwrraappssttrriinngg is handy because the RPC package passes a maximum of two XDR routines as parameters, and xxddrr__ssttrriinngg, one of the most frequently used primitives, requires three. Returns one if it succeeds, zero otherwise. SSEEEE AALLSSOO RRPPCC(3N) The followin manuals: _e_X_t_e_r_n_a_l _D_a_t_a _R_e_p_r_e_s_e_n_t_a_t_i_o_n _S_t_a_n_d_a_r_d: _P_r_o_t_o_c_o_l _S_p_e_c_i_f_- _i_c_a_t_i_o_n _e_X_t_e_r_n_a_l _D_a_t_a _R_e_p_r_e_s_e_n_t_a_t_i_o_n: _S_u_n _T_e_c_h_n_i_c_a_l _N_o_t_e_s _X_D_R: _E_x_t_e_r_n_a_l _D_a_t_a _R_e_p_r_e_s_e_n_t_a_t_i_o_n _S_t_a_n_d_a_r_d, RFC1014, Sun Microsystems, Inc., USC-ISI. Sprite v1.0 3 November 1987 8